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It's time to update the old saying "The 
job isn't over till the paperwork is 
done." When it comes to writing 
Windows applications, the job isn't 
truly over till the help system is done. 
A printed manual is no longer suffi- 
cient or even necessary, but on-line 
help is a must — and context-sensitive 
help is even better. Fortunately, 
modern tools make help-system creation 
■ simple, so there's just no excuse for skip- 
ping this step. 

Even the best tools won't do the work 
for you, though. To build a decent help 
system, you need to write clear and simple 
text that explains how your program 
works. You also need to program the con- 
nections between the topics of your help 
system. Most of all, though, you need to 
understand all the elements of a good 
help system. You can be the world's best 
programmer and still produce an inade- 
quate help system if you aren't familiar 
with all the features WINHELP.EXE 
(the built-in Windows help engine) offers. 
This article will explain the elements of a 
help system, both simple and advanced. It 
won't discuss the nitty-gritty details of 
help-system construction, since those will 
vary depending on the design tool that 
you use. 

Figure 1 is a screenshot of a sample 
help system you can refer to as you read 
this article. The sample help system was 
designed strictly to show as many help 
features as possible — it's not meant as an 
example of good layout and design! 

WRITING HELP TOPICS Just as a book 
is divided into pages, a help system is di- 
vided into topics. A topic should cover a 
single concept, and most topics should 
contain no more than one screenful of 
text. Every topic has a title and a context 



string. From the user's point of view, the 
title is the name of the topic. For example, 
when WinHelp's Search dialog displays a 
list of topics, what it shows is the titles of 
the topics. Each topic's unique context 
string identifies the topic to WinHelp in- 
ternally. Common practice is to make the 
context string the same as the title, replac- 
ing any spaces with underscores — many 
help-creation tools do this automatically. 
You can optionally assign a unique con- 
text number to each topic. Context num- 
bers are useful when working with pro- 
gramming environments like Microsoft 
Visual Basic, in which menu choices and 
on-screen controls can be linked directly 
to help-context numbers. 

Frequently one topic will refer to in- 
formation that's covered in more detail in 
another topic. A printed manual would 
use a reference like "(see page 27)"; a 
help system can incorporate a jump di- 
rectly to the other topic. A word or phrase 
is designated as the hot spot for the 
jump — the help system under- 
lines the hot-spot text and, by 
default, displays it in green. 
Jumps are sometimes called 
links or hypertext links. When 
the user clicks on a jump hot 
spot, the help system switches to 
the specified target page. To re- 
turn from one or several jumps, 
the user simply clicks Win- 
Help's Back button. 

A printed manual might in- 
sert the definition of an unfamil- 
iar word or phrase as a footnote. 
Help systems use a pop-up topic 
instead. The word or phrase 
designated as the pop-up hot 
spot is displayed in green by de- 
fault, with a dotted underline. 



Clicking on the pop-up hot spot doesn't 
switch to a new topic. Rather, it causes the 
text of the pop-up topic to appear in a 
window that seems to float above the 
main WinHelp window. Another mouse 
click disposes of the pop-up window. As 
discussed below, bitmap images in the 
help system can also be hot spots for 
jumps or pop-ups. 

Note that although the text of jump 
and pop-up hot spots is green by default, 
the user can choose different colors. 
Adding a JumpColor key to the [Win- 
dows Help] section of WIN. INI changes 
the color of both jumps and pop-ups; 
adding a PopupColor key sets the color 
of pop-ups alone. The value for each of 
these keys consists of three numbers 
from to 255 indicating the amount of 
red, green, and blue in the color. For 
example: 

JumpColor=192 
PopupColor=0 192 

would cause WinHelp to display jump hot 
spots in a medium red and pop-ups in a 
medium blue. 

NAVIGATING THE HELP SYSTEM Every 
help system must have a Contents topic; 
it's a kind of "home base" for the help sys- 
tem, and its title is usually just "Contents" 
or "<program name> Help Contents." 
This is the topic that WinHelp displays 
when no specific topic is requested, and 
WinHelp's Contents button jumps 
straight to this topic. Usually the Contents 
topic contains almost nothing but jumps 
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title Jbr this topic. 
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Figure 1: Most of the dements of this sample help system 
explain themselves. The About button and the browse 
buttons were added using help macros. 
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You don't need a fancy screen-cap- 
ture utility to take a snapshot of your 
program's main window. Run your 
program and press Alt-PrtSc to copy 
the active window to the clipboard. 
Launch Paintbrush and maximize it, 
then paste in the contents of the 



Image Attributes. In the resulting 
dialog box, click on the "pels" radio 
button (pels means pixels), and fill in 
the Width and Height boxes with the 
noted coordinates of the image's 
bottom right corner. Click OK, an- 
swer Yes to the warning that the 



1 



clipboard. (If the image is too big, try . current image will be lost, and answer 



removing the check marks next to 
Tools and Linesize and Palette under 
the View menu and paste again.) 
Now select Cursor Position from the 
View menu, and place the mouse ,<^« 
cursor precisely at the bottom right 
corner of the image. Note the x,y 
coordinates in the cursor-position 
window. 

From the Options menu, select 

to other high-level topics. You may want 
to think of the Contents topic as being 
equivalent to the table of contents in a 
book, and the jumps the Contents topic 
contains as equivalent to the beginnings 
of chapters. A simple Contents topic 
might contain jumps to topics explaining 
each of the program's windows and each 
of the top-level menu items. The user will 
see the Contents topic a lot, so it should 
be orderly and attractive. Every single ad- 
ditional topic should be accessible, via 
one route or another, from the Contents 
topic. 

The jumps in a well-written help sys- 
tem form a complicated web of connec- 
tions. One topic may include jumps to a 
dozen others, or a dozen topics may all 
have jumps to one topic. A series of jumps 
may form a loop, bringing you back to the 
starting topic. For example, in WinHelp's 
own help system the "Searching for a 
Help Topic" and "Moving Around in 
Help" topics both include jumps to each 
other. This free-association network is 
convenient for the user who's pursuing a 
particular train of thought, but it's not 
much use when you want to "skim" the 
help system. A good help system will also 
include one or more browse sequences 
(see Figure 2). A browse sequence is a lin- 
ear series of related help topics intended 
to be read in order. Each topic can belong 
to one and only one browse sequence. 
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No to the query about saving current 
changes. Now paste the clipboard into 
Paintbrush again. If you've done 
everything right, the image will pre- 
cisely fit the working area of Paint- 
brush. Select Save As from the File 
menu, and set the file type to "16 
color bitmap." Choose a name and 
save the file. You've snapped the 



When the current topic belongs to a 
browse sequence, WinHelp's browse but- 
tons (marked with « and ») are en- 
abled. Pressing a browse button flips to 
the previous or next topic in the current 
browse sequence. 

How do you decide which topics to 
link in a browse sequence? It's up to you, 
of course, but here are some guidelines. 
In a very small help system, you'll create 
a single browse sequence that includes 
every topic. Start with the Contents topic 
and add the remaining topics in any 
order that makes sense to you. In a 
larger help system, 
start a browse se- 
quence with each of 
the "chapter heading" 
topics reached by a 
single jump from the 
Contents topic. Again, 
arrange the topics in 
an order that makes 
sense to you, and 
make sure that every 
topic is included in 
one browse sequence. 

Keywords are 
words and phrases — — 
that serve as the help system's index. Each 
topic can have any number of associated 
keywords, though more than three or four 
is unusual. WinHelp's Search dialog ini- 
tially displays a list of all keywords in the 



lect one, the lower list box fills with a list 
of all topics associated with that keyword 
(sec Figure 3). Keywords give the user J 
quick way to dive into a particular topic. 
Note that a keyword need not appear lit- 
erally in the topic's text. 

Assigning keywords to topics can be 
a tedious task, but it's extremely impor- 
tant. Pick descriptive words and phrases 
for keywords, and assign at least one 
keyword to every topic. If nothing else, 
use the topic's title as a keyword. It's 
very important to be consistent in your 
keywords. Don't use "open files" for 
one topic and "open file" for another, 
for example. Some help-design tools 
make it easy to reuse existing keyword!. 
If yours doesn't, it's a good idea to keep 
a list of the keywords you've already 
added to the system, and reuse then 
when possible. 

WORKING WITH GRAPHICS Windowsis 
a graphical user interface, and Window 
help systems are definitely improved bj 
the judicious use of bitmapped graphics. 
Graphics may be purely decorative, likes 
company logo on the Contents topic, « 
they may be an active part of the help sys- 
tem with embedded hot spots. The tech- 
nical term for bitmaps that include hot 
spots is segmented hypergraphics, and Mi- 
crosoft's freely available SHED editor 
can turn an ordinary bitmap into a seg- 
mented hypergraphic (.SHG) file. A 
graphical hot spot is linked to its topic vis 
the topic's context string. Modern help 
■ ■■: ■ lis if n.< 
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Figure 2: In this simple help system, Jumps (blue arrows) make a web 
of connections between the topics. The browse sequence (red arrow) 
is a linear path through the help system that visits every topic 
exactly once. 



systems often incorporate a bitmap of the 
program's main screen, in which a graph- 
ic hot spot for each on-screen element of 
the main windowjumps to a help topic ex- 
plaining that element. 
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■ Choosing Your Tools 



It's possible to build a help system 
using just three tools: a Windows 
word processor that can generate 
.RTF (Rich .Text Format) files, the 
Windows Help Compiler, and the 



dows Help Files," PC Magazine, 
August 1994), and Doc-to-Help, 
from WexTech Systems ("Word 
Processor Add-Ins," February 9, 
1993), work with your word proces- 



SHED graphics editor. You can sor to generate the necessary RTF 



download the latter two from Com 



puServe's WINSDK forum. Libra: 
... 16, as HCP.ZIPandSHED.ZIP. But 



; writing a help system this way is as 
tedious and counterproductive as 
assembling the bytes of your Win- 
dows application using DEBUG. 
. Modern tools such as RoboHelp, . . 
from Blue Sky Software Corp. (re- 
viewed in "Word Processing Utilities: 



In many cases, the tools Windows itself 
provides are sufficient to let you create a 
bitmap of your program's main window, 
as the sidebar "Snapping Your Screens" 
explains. Regardless of whether or not 
you intend to create graphical hot spots in 
the bitmap, you should load it into the 
SHED editor and save it as an .SHG file. 
Why? Because the .SHG file format uses 
compression, and the .BMP format does 
not. An .SHG file can be substantially 
smaller than a corresponding .BMP file. 
To create a graphical hot spot in the 
SHED editor, you use the mouse to drag 
a rectangle that defines the hot spot area, 
and you associate the hot spot area with 
the context string of the corresponding 
help-system topic as shown in Figure 4. 

Bitmaps make your help file bigger, 
even when stored as compressed .SHG 
files. Don't overuse them! For a simple 
program, one picture of the main win- 
dow may be enough. And remember that 
although help text in topics wraps when 
the help window is resized, bitmaps 
can't. Always use the smallest bitmap 
that will do. 

USING HELP MACROS A basic help sys- 
tem consists of help topics linked by 
jumps and browse sequences, with a set of 
keywords to serve as an index. It may in- 
clude bitmapped graphics as well. How- 
ever, to go beyond the basics you'll need 
to learn about help macros. The jump and 
pop-up hot spots that you embed in help 



file. Other tools such as The Win- 
dows Help Magician, from Software 
Interphase ("Create I lelp Files 
Quickly With The Help Magician," 
July 1993), and ForeHelp, from Fore- 
Front ("ForeHelp: Help-File Heav- 
en," October 25, 1994), provide their 
own WYSIWYG help editors. This is 
not an exhaustive list; there are help- 
design tools to suit every need and 



topics are effectively commands to Win- 
Help, telling it to jump to a particular 
topic or display a pop-up window. Help 
macros are another kind of command for 
WinHelp. There arc over 50 macros thai 
can be programmed to activate when the 
help system loads, when a particular topic- 
is activated, or when the user clicks on a 
hot spot. This article won't attempt an ex- 
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Select a topic, then choose Go To. 



Delminq and Using Bookmaiki 



Figure 3: The top list box of WinHelp's Search dialog lists all 
keywords In the help system; the bottom list box shows all 
topics related to the selected keyword. 



haustive discussion of each help macro; 
what's important is that you understand 
the kinds of commands thai are available. 

A dozen or so of the macro commands 
let you create, delete, enable, disable, and 
change the effect of a WinHelp menu 
item or button. The result (called the 



binding) of activating a menu item or but- 
ton is always a macro. Another 20-odd 
macro commands duplicate the effect of 
WinHelp's built-in menu and button com- 
mands. For example, the Next macro 
switches to the next topic in the current 
browse sequence, and the About macro 
displays WinHelp's About box. In the 
sample help system shown in Figure 1, 
this macro creates the About button and 
binds it to the About macro: 

CreuLollutton ('About*, '(.About' , 
'About ( I ' ) 

Yet another group of macros gives com- 
plete control over jumps and pop-ups 
within this file or into any other help file. 

Possibly the most common macro 
command is BrowseButtons. which adds 
the standard browse buttons to Win- 
Help's button bar and is usually activated 
at the time the help system loads. Your 
help system should include browse se- 
quences, so you'll definitely need to use 
BrowseButtons. Some help-design tools 
automatically include the BrowseButtons 
macro when any browse sequences are 
present. 

Certainly the flashiesl WinHelp macro 
commands are ExecProgram and Regis- 
terRoutine. ExecProgram 
launches the Windows applica- 
tion of your choice. You might, 
for example, create a button 
that activates a computer-based 
training program using Exec- 
Program. Rcgi si c i Ro u l i nc 
gives your help system access to 
any Windows API function or 
any function defined in a DLL 
(Dynamic Link Library). Once 
a function is registered, you call 
it just as if it were another 
macro. RegisterRoutine is often 
used lo add multimedia support 
to help files: for example, to 
play a .WAV file for pronuncia- 
tion when the user clicks on an 
— ——— unusual word. 

DETAILING THE HELP SYSTEM Expert 
help-system designers can add a number 
of refinements. Give a finishing touch to 
the text in your help topics by using multi- 
ple fonts and font effects such as bold, ital- 
ic, and underline. Since you don't know 
what fonts your users will have installed, 
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Figure 4: In this sample bitmap of a program's main 
window, oach menu Item anil icon Is designated as a 
graphical hot spot The Attributes dialog box Is displaying 
details about the window-menu hot spot 



you should only use the fonts Microsoft 
Windows 3.1 loads by default: Arial, 
Courier New, MS Serif, MS Sans Serif, 
Symbol, Times New Roman, and 
Wingdings. 

Topic text wraps to fit the width of 
the WinHelp window. If it won't all fit, a 
vertical scroll bar appears. Once the user 
scrolls into the topic, the topic heading 
isn't visible! If you put the topic heading 
in a non-scrolling region, it won't disap- 
pear when the text scrolls. You can give 
the non-scrolling region its own back- 
ground color too, as Figure 1 shows. 

If your help system needs to present 
tabular data, don't torture yourself trying 
to line up items using Tab characters. 
WinHelp includes direct support for 
tables. But creating a table "by hand" 
using WinHelp codes is incredibly tedious 
and difficult. This is one case where a 
good design tool is absolutely essential. 

In some instances it makes sense to en- 
hance your help system with one or more 
secondary windows. For example, the 
help system in Microsoft Word for Win- 
dows, Version 6.0 uses a secondary win- 
dow for "How To" topics, and the help 
system for many programming environ- 
ments uses a secondary window to show 
examples of the use of various program el- 
ements. Figure 1 includes a secondary 
window; note that the secondary window 
has no menu or button bar. 

HOW SENSITIVE SHOULD YOU BEP Your 
program's help system need not be con- 
text-sensitive. As long as it includes the 
standard help-menu items, the user can 
instantly view the Contents topic or 
search for help on a given keyword. If the 
help system is well organized, context- 
sensitive help may not be necessary. On 
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the other hand, if the develop- 
ment environment you're using 
has support for context-sensi- 
tive help built in, you can give 
every window, every menu 
item, and every on-screen con- 
trol its own personal help topic. 

Precisely how context-sensi- 
tive you make your help system 
is a case-by-case matter and 
can't be defined by rules. My 
own suggestion, however, is a 
compromise between no con- 
text-sensitive help and a topic 
— — — for every push button. If your 
program has multiple windows and dialog 
boxes, devote a help topic to each of 
these, and write your code so that pressing 
Fl (the standard help key) brings up the 
help topic for the current window. For 
menu items and controls, display a single- 
line "hint" on the program's status bar for 
the menu item or control that currently 
has the focus. If your development envi- 
ronment supports it, create "flyover help" 
or "tooltips" for toolbar items. Flyover 
help, as shown in Figure S, is a tiny box 




Figure 5: This demo application shows a flyover 
help box for one of Its SpeedBar buttons and i 
hint line In the status bar at the bottom. 



that appears when you rest the mouse cur- 
sor on a particular button or other toolbar 
item for more than a second or two. 

Now that you know what elements 
make up a good help system, you're ready 
to choose your tools (see the sidebar 
"Choosing Your Tools") and get to work. 
With a good design tool and the knowledge 
you've gained from this article, you should 
be able to enhance your programs with a 
thoroughly professional help system. □ 
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